home *** CD-ROM | disk | FTP | other *** search
/ ETO Development Tools 2 / ETO Development Tools 2.iso / Tools - Objects / MacApp / MacApp CD Release / MacApp 2.0.1 (Many Libraries) / Interfaces / PInterfaces / UMacAppUtilities.p < prev    next >
Encoding:
Text File  |  1990-10-25  |  41.1 KB  |  1,122 lines  |  [TEXT/MPS ]
  1. {[a-,body+,h-,o=100,r+,rec+,t=4,u+,#+,j=20/57/1$,n-]}
  2. { UMacAppUtilities.p }
  3. { Copyright © 1984-1990  Apple Computer, Inc.  All rights reserved. }
  4. {
  5. This unit implements a set of simple type declarations and utility
  6. routines.
  7. }
  8.  
  9. {$IFC UNDEFINED UsingIncludes}
  10. {$SETC UsingIncludes := FALSE}
  11. {$ENDC}
  12.  
  13. {$IFC NOT UsingIncludes}
  14. UNIT UMacAppUtilities;
  15.  
  16.     INTERFACE
  17.         {$ENDC}
  18.  
  19.         {$IFC UNDEFINED __UMacAppUtilities__}
  20.         {$SETC __UMacAppUtilities__ := FALSE}
  21.         {$ENDC}
  22.  
  23.         {$IFC NOT __UMacAppUtilities__}
  24.         {$SETC __UMacAppUtilities__ := TRUE}
  25.  
  26.         { • Directive settings to EXPORT }
  27.         {$IFC qDebug}
  28.         {$W-}
  29.         {$ELSEC}
  30.         {$W+}
  31.         {$ENDC}
  32.  
  33.         {$IFC qUnInit}
  34.         {$Init+}
  35.         {$ELSEC}
  36.         {$Init-}
  37.         {$ENDC}
  38.  
  39.         {$IFC qRangeCheck}
  40.         {$R+}
  41.         {$OV+}
  42.         {$ELSEC}
  43.         {$R-}
  44.         {$OV-}
  45.         {$ENDC}
  46.  
  47.         {$IFC qTrace}
  48.         {$D++}
  49.         {$N+}
  50.         {$ELSEC}
  51.         {$IFC qNames}
  52.         {$D+}
  53.         {$N+}
  54.         {$ELSEC}
  55.         {$D-}
  56.         {$N-}
  57.         {$ENDC}
  58.         {$ENDC}
  59.  
  60.         { • Auto-Include the requirements for this unit's interface. }
  61.         {$SETC UMacAppUtilitiesIncludes := UsingIncludes}
  62.         {$SETC UsingIncludes := TRUE}
  63.         {$I+}
  64.         {$IFC UNDEFINED UsingTextEdit} {$I TextEdit.p} {$ENDC}
  65.         {$IFC UNDEFINED UsingFiles} {$I Files.p} {$ENDC}
  66.         {$IFC UNDEFINED UsingTraps} {$I Traps.p} {$ENDC}
  67.         {$IFC UNDEFINED UsingScrap} {$I Scrap.p} {$ENDC}
  68.         {$IFC UNDEFINED __ULoMem__} {$I ULoMem.p} {$ENDC}
  69.         {$SETC UsingIncludes := UMacAppUtilitiesIncludes}
  70.  
  71.         CONST
  72.         { In the NON-debug case these are set to false and the code they condition will not be
  73.         compiled }
  74.             {$IFC NOT qDebug}
  75.             gPreCondition        = FALSE;                { true to do pre-condition processing }
  76.             gPostCondition        = FALSE;                { true to do post-condition processing }
  77.             {$ENDC}
  78.  
  79.             { set constants from the standard compiletime variables.
  80.             These constants may be used in expressions such that if the expression statically evaluates
  81.             to false then the compiler will omit conditioned code.
  82.  
  83.             if NOT qNeedsColorQD THEN
  84.                 mumble;
  85.  
  86.             }
  87.             {[f-]}
  88.             { If for some reason these don't come in from MABuild set them to the highest common form
  89.             -NoDebug -System6
  90.             }
  91.             {$IFC UNDEFINED qHasForward}    { Compiler Has FORWARD and EXTERNAL capabilities }
  92.             {$SETC qHasForward := FALSE}
  93.             {$EndC}
  94.  
  95.             {$IFC UNDEFINED qDebug}
  96.             {$SETC qDebug := FALSE}
  97.             {$EndC}
  98.  
  99.             {$IFC UNDEFINED qDebugTheDebugger}
  100.             {$SETC qDebugTheDebugger := FALSE}
  101.             {$EndC}
  102.  
  103.             {$IFC UNDEFINED qInspector}
  104.             {$SETC qInspector := FALSE}
  105.             {$EndC}
  106.  
  107.             {$IFC UNDEFINED qMacApp}
  108.             {$SETC qMacApp := TRUE}
  109.             {$EndC}
  110.  
  111.             {$IFC UNDEFINED qNames}
  112.             {$SETC qNames := FALSE}
  113.             {$EndC}
  114.  
  115.             {$IFC UNDEFINED qNeedsColorQD}
  116.             {$SETC qNeedsColorQD := FALSE}
  117.             {$EndC}
  118.  
  119.             {$IFC UNDEFINED qNeedsFPU}
  120.             {$SETC qNeedsFPU := FALSE}
  121.             {$EndC}
  122.  
  123.             {$IFC UNDEFINED qNeedsHierarchicalMenus}
  124.             {$SETC qNeedsHierarchicalMenus := TRUE}
  125.             {$EndC}
  126.  
  127.             {$IFC UNDEFINED qNeedsMC68020}
  128.             {$SETC qNeedsMC68020 := FALSE}
  129.             {$EndC}
  130.  
  131.             {$IFC UNDEFINED qNeedsMC68030}
  132.             {$SETC qNeedsMC68030 := FALSE}
  133.             {$EndC}
  134.  
  135.             {$IFC UNDEFINED qNeedsROM128K}
  136.             {$SETC qNeedsROM128K := TRUE}
  137.             {$EndC}
  138.  
  139.             {$IFC UNDEFINED qNeedsScriptManager}
  140.             {$SETC qNeedsScriptManager := TRUE}
  141.             {$EndC}
  142.  
  143.             {$IFC UNDEFINED qNeedsStyleTextEdit}
  144.             {$SETC qNeedsStyleTextEdit := TRUE}
  145.             {$EndC}
  146.  
  147.             {$IFC UNDEFINED qNeedsWaitNextEvent}
  148.             {$SETC qNeedsWaitNextEvent := TRUE}
  149.             {$EndC}
  150.  
  151.             {$IFC UNDEFINED qPerform}
  152.             {$SETC qPerform := FALSE}
  153.             {$EndC}
  154.  
  155.             {$IFC UNDEFINED qRangeCheck}
  156.             {$SETC qRangeCheck := FALSE}
  157.             {$EndC}
  158.  
  159.             {$IFC UNDEFINED qTemplateViews}
  160.             {$SETC qTemplateViews := TRUE}
  161.             {$EndC}
  162.  
  163.             {$IFC UNDEFINED qTrace}
  164.             {$SETC qTrace := FALSE}
  165.             {$EndC}
  166.  
  167.             { Flag that indicates that the user wants to play around with the new, UNSUPPORTED
  168.             stuff that we on the MacApp team are fiddling with.
  169.  
  170.             WARNING, Setting this flag true voids your MacApp warranty.  It is used to condition
  171.             features that are experimental and UNSUPPORTED.  Features enabled with this flag
  172.             may or may not be included in future versions of MacApp and are here for informational
  173.             purposes only.
  174.  
  175.             'Nuff said. }
  176.  
  177.             {$IFC UNDEFINED qExperimentalAndUnsupported}
  178.             {$SETC qExperimentalAndUnsupported := FALSE}
  179.             {$EndC}
  180.  
  181.  
  182.  
  183.             {$IFC UNDEFINED __cplusplus}                { in C++ the compile variables can be used
  184.                                                         in expressions }
  185.             {$IFC qDebug}                    qDebug = TRUE;
  186.             {$ElseC}                        qDebug = FALSE;                 {$EndC}
  187.             { If qDebug then this flag is TRUE else FALSE. }
  188.  
  189.             {$IFC qDebugTheDebugger}        qDebugTheDebugger = TRUE;
  190.             {$ElseC}                        qDebugTheDebugger = FALSE;        {$EndC}
  191.             { If qDebugTheDebugger then this flag is TRUE else FALSE. }
  192.  
  193.             {$IFC qInspector}                qInspector = TRUE;
  194.             {$ElseC}                        qInspector = FALSE;             {$EndC}
  195.             { If qInspector then this flag is TRUE else FALSE. }
  196.  
  197.             {$IFC qMacApp}                    qMacApp = TRUE;
  198.             {$ElseC}                        qMacApp = FALSE;                {$EndC}
  199.             { If qMacApp then this flag is TRUE else FALSE. }
  200.  
  201.             {$IFC qNames}                    qNames = TRUE;
  202.             {$ElseC}                        qNames = FALSE;                 {$EndC}
  203.             { If qNames then this flag is TRUE else FALSE. }
  204.  
  205.             {$IFC qNeedsColorQD}            qNeedsColorQD = TRUE;
  206.             {$ElseC}                        qNeedsColorQD = FALSE;            {$EndC}
  207.             { If qNeedsColorQD then this flag is TRUE else FALSE. }
  208.  
  209.             {$IFC qNeedsFPU}                qNeedsFPU = TRUE;
  210.             {$ElseC}                        qNeedsFPU = FALSE;                {$EndC}
  211.             { If qNeedsFPU then this flag is TRUE else FALSE. }
  212.  
  213.             {$IFC qNeedsHierarchicalMenus}    qNeedsHierarchicalMenus = TRUE;
  214.             {$ElseC}                        qNeedsHierarchicalMenus = FALSE; {$EndC}
  215.             { If qNeedsHierarchicalMenus then this flag is TRUE else FALSE. }
  216.  
  217.             {$IFC qNeedsMC68020}            qNeedsMC68020 = TRUE;
  218.             {$ElseC}                        qNeedsMC68020 = FALSE;            {$EndC}
  219.             { If qNeedsMC68020 then this flag is TRUE else FALSE. }
  220.  
  221.             {$IFC qNeedsMC68030}            qNeedsMC68030 = TRUE;
  222.             {$ElseC}                        qNeedsMC68030 = FALSE;            {$EndC}
  223.             { If qNeedsMC68030 then this flag is TRUE else FALSE. }
  224.  
  225.             {$IFC qNeedsROM128K}            qNeedsROM128K = TRUE;
  226.             {$ElseC}                        qNeedsROM128K = FALSE;            {$EndC}
  227.             { If qNeedsROM128K then this flag is TRUE else FALSE. }
  228.  
  229.             {$IFC qNeedsScriptManager}        qNeedsScriptManager = TRUE;
  230.             {$ElseC}                        qNeedsScriptManager = FALSE;    {$EndC}
  231.             { If qNeedsScriptManager then this flag is TRUE else FALSE. }
  232.  
  233.             {$IFC qNeedsStyleTextEdit}        qNeedsStyleTextEdit = TRUE;
  234.             {$ElseC}                        qNeedsStyleTextEdit = FALSE;    {$EndC}
  235.             { If qNeedsStyleTextEdit then this flag is TRUE else FALSE. }
  236.  
  237.             {$IFC qNeedsWaitNextEvent}        qNeedsWaitNextEvent = TRUE;
  238.             {$ElseC}                        qNeedsWaitNextEvent = FALSE;    {$EndC}
  239.             { If qNeedsWaitNextEvent then this flag is TRUE else FALSE. }
  240.  
  241.             {$IFC qPerform}                 qPerform = TRUE;
  242.             {$ElseC}                        qPerform = FALSE;                {$EndC}
  243.             { If qPerform then this flag is TRUE else FALSE. }
  244.  
  245.             {$IFC qRangeCheck}                qRangeCheck = TRUE;
  246.             {$ElseC}                        qRangeCheck = FALSE;            {$EndC}
  247.             { If qRangeCheck then this flag is TRUE else FALSE. }
  248.  
  249.             {$IFC qTemplateViews}            qTemplateViews = TRUE;
  250.             {$ElseC}                        qTemplateViews = FALSE;         {$EndC}
  251.             { If qTemplateViews then this flag is TRUE else FALSE. }
  252.  
  253.             {$IFC qTrace}                    qTrace = TRUE;
  254.             {$ElseC}                        qTrace = FALSE;                 {$EndC}
  255.             { If qTrace then this flag is TRUE else FALSE. }
  256.  
  257.             {$IFC qExperimentalAndUnsupported}qExperimentalAndUnsupported = TRUE;
  258.             {$ElseC}                        qExperimentalAndUnsupported = FALSE;{$EndC}
  259.             { If qExperimentalAndUnsupported then this flag is TRUE else FALSE. }
  260.  
  261.             {$EndC}
  262.             {[f+]}
  263.  
  264.             { ASCII Character Constants }
  265.             chBackspace         = CHR(8);                { ASCII code for Backspace character }
  266.             chClear             = CHR(27);                { ASCII code for Clear key (aka ESC) }
  267.             chDown                = CHR(31);                { ASCII code for down arrow }
  268.             chEnd                = CHR(4);                { ASCII code for the End key }
  269.             chEnter             = CHR(3);                { ASCII code for Enter character }
  270.             chEscape            = CHR(27);                { ASCII code for Escape (aka Clear) key }
  271.             chFunction            = CHR(16);                { ASCII code for any function key }
  272.             chFwdDelete         = CHR($7F);             { ASCII code for forward delete }
  273.             chHelp                = CHR(5);                { ASCII code for Help key }
  274.             chHome                = CHR(1);                { ASCII code for the Home key }
  275.             chLeft                = CHR(28);                { ASCII code for left arrow }
  276.             chPageDown            = CHR(12);                { ASCII code for Page Down key }
  277.             chPageUp            = CHR(11);                { ASCII code for Page Up key }
  278.             chReturn            = CHR(13);                { ASCII code for Return character }
  279.             chRight             = CHR(29);                { ASCII code for right arrow }
  280.             chSpace             = CHR(32);                { ASCII code for Space character }
  281.             chTab                = CHR(9);                { ASCII code for Tab character }
  282.             chUp                = CHR(30);                { ASCII code for up arrow }
  283.  
  284.             { Virtual Key Code Constants }
  285.             kClearVirtualCode    = 71;                    { Clear key virtual code }
  286.             kEscapeVirtualCode    = 53;                    { Escape key virtual code }
  287.             kF10VirtualCode     = 109;                    { F10 virtual key code }
  288.             kF11VirtualCode     = 103;                    { F11 virtual key code }
  289.             kF12VirtualCode     = 111;                    { F12 virtual key code }
  290.             kF13VirtualCode     = 105;                    { F13 virtual key code }
  291.             kF14VirtualCode     = 107;                    { F14 virtual key code }
  292.             kF15VirtualCode     = 113;                    { F15 virtual key code }
  293.             kF1VirtualCode        = 122;                    { F1 virtual key code }
  294.             kF2VirtualCode        = 120;                    { F2 virtual key code }
  295.             kF3VirtualCode        = 99;                    { F3 virtual key code }
  296.             kF4VirtualCode        = 118;                    { F4 virtual key code }
  297.             kF5VirtualCode        = 96;                    { F5 virtual key code }
  298.             kF6VirtualCode        = 97;                    { F6 virtual key code }
  299.             kF7VirtualCode        = 98;                    { F7 virtual key code }
  300.             kF8VirtualCode        = 100;                    { F8 virtual key code }
  301.             kF9VirtualCode        = 101;                    { F9 virtual key code }
  302.             kFwdDelVirtualCode    = 117;                    { Forward Delete virtual code }
  303.  
  304.             kSysFontName        = '';                    { GetFontNum converts this to zero. }
  305.             kApplFontName        = 'A';                    { GetFontNum converts this to one. }
  306.  
  307.             kWordAlign            = TRUE;                 { Constant for OffsetPtr }
  308.             kDontAlign            = FALSE;                { Constant for OffsetPtr }
  309.  
  310.             kHexDigits            = '0123456789ABCDEF';    { Digits in base 16 }
  311.  
  312.             kNoFileRefnum        = - (MaxInt - 1);        { an invalid file refnum; used to indicate
  313.                                                          an unopened file (actually interpreted by
  314.                                                          HFS as a volume number. If you have this
  315.                                                          many volumes you are sick indeed! }
  316.             kNoStaticLink        = - 1;                    { Pascal functions and procedures can take
  317.                                                          "procedure" parameters which are like C++
  318.                                                          function pointers with the additional
  319.                                                          capabilitly to access upscope variables.
  320.                                                          This is particularly convenient for "call
  321.                                                          back" type procedures because they are
  322.                                                          executed in their original scope. Well
  323.                                                          kids, C++ has no equivalent structure, so
  324.                                                          all of the interfaces that call for a
  325.                                                          "procedure" parameter have been translated
  326.                                                          to a function pointer and a static link
  327.                                                          (upscope variable accessor) in the C++
  328.                                                          headers. The static link can be used to
  329.                                                          pass any useful context information
  330.                                                          around, see the C++ examples. HOWEVER,
  331.                                                          when a static link is not used or
  332.                                                          required; C++ users must insert a non-NIL
  333.                                                          placeholder. The receiving code is in
  334.                                                          pascal and includes special detection of
  335.                                                          the case where NIL is passed for static
  336.                                                          link. When NIL is passed in, >>> NO <<<
  337.                                                          static link will be passed to the
  338.                                                          "procedure" parameter when it is called!
  339.                                                          You can imagine the ensuing heartache for
  340.                                                          well meaning C++ users as their stack gets
  341.                                                          tromped. The answer, my friends is to have
  342.                                                          C++ users pass kNoStaticLink when they
  343.                                                          don't wish to use the static link. }
  344.  
  345.             { Field types for the Fields methods. These are understood by StdFieldToString.
  346.             Negative values are reserved for MacApp.
  347.             }
  348.             bBoolean            = - 1;
  349.             bByte                = - 2;
  350.             bChar                = - 3;
  351.             bClass                = - 4;
  352.             bCmdNumber            = - 5;
  353.             bCntlAdornment        = - 6;
  354.             bControlHandle        = - 7;
  355.             bDouble             = - 8;                    { SANE Double }
  356.             bExtended            = - 9;                    { SANE Extended }
  357.             bFixed                = - 10;
  358.             bFontName            = - 11;
  359.             bGrafPtr            = - 12;
  360.             bHandle             = - 13;
  361.             bHexInteger         = - 14;
  362.             bHexLongInt         = - 15;
  363.             bHighByte            = - 16;
  364.             bHLState            = - 17;
  365.             bIDType             = - 18;
  366.             bInteger            = - 19;
  367.             bLongInt            = - 20;
  368.             bLowByte            = - 21;
  369.             bObject             = - 22;
  370.             bOSType             = - 23;
  371.             bPattern            = - 24;
  372.             bPoint                = - 25;
  373.             bPointer            = - 26;
  374.             bReal                = - 27;                 { Pascal Real }
  375.             bRect                = - 28;
  376.             bResType            = - 29;
  377.             bRGBColor            = - 30;
  378.             bRgnHandle            = - 31;
  379.             bSingle             = - 32;                 { SANE Single }
  380.             bSizeDeterminer     = - 33;
  381.             bString             = - 34;
  382.             bStringHandle        = - 35;
  383.             bStyle                = - 36;
  384.             bTEHandle            = - 37;
  385.             bTitle                = - 38;
  386.             bVCoordinate        = - 39;
  387.             bVPoint             = - 40;
  388.             bVHSelect             = - 41;
  389.             bVRect                = - 42;
  390.             bWindowPtr            = - 43;
  391.  
  392.             {$IFC FALSE}                                { !!! can't fieldtostring for multiline
  393.                                                          structures yet (2.0)}
  394.             bTextStyle            = - 44;
  395.             bConfigRec            = - 45;
  396.             bScrapStuff         = - 46;
  397.             {$EndC}
  398.  
  399.             kMANameSize         = 63;                    { Maximum size string supported for an
  400.                                                          MAName }
  401.  
  402.             kAutoWrap            = TRUE;                 { Want to AutoWrap (for MATextBox)}
  403.             kNoAutoWrap         = NOT kAutoWrap;        { Don't want to AutoWrap (for MATextBox)}
  404.             kEraseFirst         = TRUE;                 { Want to erase first (for MATextBox)}
  405.             kNoEraseFirst        = NOT kEraseFirst;        { Don't want to erase first (for MATextBox)}
  406.             kSpaceForCaret        = TRUE;                    { Want to leave space for an insertion caret
  407.                                                         (for MATextBox)}
  408.             kNoSpaceForCaret    = NOT kSpaceForCaret;    { Don't want to leave space for an insertion 
  409.                                                         caret (for MATextBox)}
  410.             teJustSystem        = teJustLeft;            { teJustLeft really means use the system
  411.                                                         justification set by the installed script.
  412.                                                         in Arabic and Hebrew systems this is typically
  413.                                                         right justification (but user changeable).
  414.                                                         using a constant with a better name like
  415.                                                         teJustSystem helps to make this issue more
  416.                                                         visible to the developer.  If LEFT
  417.                                                         justification is REQUIRED there is of course,
  418.                                                         teForceLeft. }
  419.  
  420.  
  421.         TYPE
  422.             { Some handy types }
  423.             { MacApp used to indicate the pointer datatype by prepending the type name with a "P"
  424.             and a handle datatype by prepending the type name with a "H".  In order to be more
  425.             compatible with the standards used in the toolbox interfaces we will now indicate pointer
  426.             datatypes by appending "Ptr" to the typename and handle datatypes by appending "Handle" to
  427.             the typename.  The old style names are left in for compatibility in Release 2.0 }
  428.  
  429.             IntegerPtr            = ^INTEGER;             { Preferred }
  430.             IntegerHandle        = ^IntegerPtr;            { Preferred }
  431.  
  432.             LongIntPtr            = ^LONGINT;             { Preferred }
  433.             LongIntHandle        = ^LongIntPtr;            { Preferred }
  434.  
  435.             BooleanPtr            = ^BOOLEAN;             { Preferred }
  436.             BooleanHandle        = ^BooleanPtr;            { Preferred }
  437.  
  438.             SignedBytePtr        = ^SignedByte;            { Preferred }
  439.             SignedByteHandle    = ^SignedBytePtr;        { Preferred }
  440.  
  441.             PInteger            = IntegerPtr;            { Left in for compatibility (2.0) }
  442.             HInteger            = IntegerHandle;        { Left in for compatibility (2.0) }
  443.             PLongInt            = LongIntPtr;            { Left in for compatibility (2.0) }
  444.             HLongInt            = LongIntHandle;        { Left in for compatibility (2.0) }
  445.             PBoolean            = BooleanPtr;            { Left in for compatibility (2.0) }
  446.             PByte                = SignedBytePtr;        { Left in for compatibility (2.0) }
  447.  
  448.             String8             = STRING[8];
  449.  
  450.             MAName                = STRING[kMANameSize];    { A Name in MacApp®. ClassNames,
  451.                                                          MethodNames, IVar Names, ProcNames, etc.
  452.                                                          ??? Should we punt on stringlength and
  453.                                                          only define pointers to these strings? }
  454.             MANamePtr            = ^MAName;                { Preferred }
  455.             MANameHandle        = ^MANamePtr;            { Preferred }
  456.             PMAName             = MANamePtr;            { Left in for compatibility (2.0) }
  457.             HMAName             = MANameHandle;         { Left in for compatibility (2.0) }
  458.  
  459.             IDType                = ResType;                { MacApp uses four byte "signatures" in
  460.                                                          several places. They are a handy way to
  461.                                                          have a partially human readable quantity
  462.                                                          that only takes up a long. }
  463.  
  464.             AdornPieces         = (adnLineTop,            { Draw a line at the top of the extent }
  465.                                    adnLineLeft,         { Draw a line on the left side of the extent
  466.                                                          }
  467.                                    adnLineBottom,        { Draw a line on the bottom side of the
  468.                                                          extent }
  469.                                    adnLineRight,        { Draw a line on the right side of the
  470.                                                          extent }
  471.                                    adnDummy,            { Place filler… }
  472.                                    adnOval,             { Do a FrameOval using the extent }
  473.                                    adnRRect,            { Do a (16,16) FrameRoundRect using the
  474.                                                          extent }
  475.                                    adnShadow);            { Draw drop shadows against framed
  476.                                                          selections }
  477.             CntlAdornment        = SET OF AdornPieces;
  478.  
  479.             VCoordinate         = LONGINT;                { VCoordinates are 32 bits as compared to QD
  480.                                                          Coordinates which are 16 bits }
  481.  
  482.             VPointSelector        = (VPtPair, VPtArray);    { so C++ unions can have names }
  483.             VPoint                = RECORD                { VPoints are synonomous with QD Point, only
  484.                                                          in 32 bit space }
  485.                 CASE VPointSelector OF
  486.                     VPtPair:
  487.                         (v, h:                 VCoordinate);
  488.                     VPtArray:
  489.                         (vh:                 ARRAY [VHSelect] OF VCoordinate);
  490.                 END;
  491.  
  492.             VRectSelector        = (VRQuad, VRPair);
  493.             VRect                = RECORD                { VRects are synonomous with QD Rects, only
  494.                                                          in 32 bit space }
  495.                 CASE VRectSelector OF
  496.                     VRQuad:
  497.                         (top, left, bottom, right: VCoordinate);
  498.                     VRPair:
  499.                         (topLeft, botRight:  VPoint);
  500.                 END;
  501.  
  502.             ConfigRecord        = RECORD                { ??? should this be PACKED ??? if so, how
  503.                                                          will this affect C++ users? }
  504.             { Values from SysEnvirons (Version 1) }
  505.                 environsVersion:    INTEGER;
  506.                 machineType:        INTEGER;
  507.                 systemVersion:        INTEGER;
  508.                 processor:            INTEGER;
  509.                 hasFPU:             BOOLEAN;
  510.                 hasColorQD:         BOOLEAN;
  511.                 keyboardType:        INTEGER;
  512.                 atDrvrVersNum:        INTEGER;
  513.                 sysVRefNum:         INTEGER;
  514.                                 { Derived values }
  515.                 hasROM128K:         BOOLEAN;            { ROM 128K - OR - Better }
  516.                 hasHFS:             BOOLEAN;
  517.  
  518.                 hasHierarchicalMenus: BOOLEAN;
  519.                 hasScriptManager:    BOOLEAN;
  520.                 hasStyleTextEdit:    BOOLEAN;
  521.                 hasSoundManager:    BOOLEAN;
  522.                 hasWaitNextEvent:    BOOLEAN;
  523.                 hasSCSI:            BOOLEAN;
  524.                 hasDesktopBus:        BOOLEAN;
  525.                 hasAUX:             BOOLEAN;
  526.                 hasTempMem:         BOOLEAN;            { TRUE if Multifinder™ temp memory is avail
  527.                                                          }
  528.                 has32BitQD:            BOOLEAN;            { TRUE if 32 bit Quickdraw is installed }
  529.                 END;
  530.  
  531.         VAR
  532.             {$IFC qDebug}
  533.             gPreCondition:        BOOLEAN;                { true to do pre-condition processing }
  534.             gPostCondition:     BOOLEAN;                { true to do post-condition processing }
  535.             {$ENDC}
  536.  
  537.             gApplicationRefNum: INTEGER;                { RefNum of the application's res file. }
  538.             gConfiguration:     ConfigRecord;            { The _actual_ environment configuration }
  539.             gMBarHeight:        INTEGER;                { Height of the menu bar in pixels }
  540.  
  541.             gBoolString:        ARRAY [BOOLEAN] OF STRING[5]; { Used to display boolean values. }
  542.             {$Push} {$J+}
  543.             GFIELDTOSTRRTN:     ProcPtr;                { Routine that converts fields to strings. }
  544.             {$Pop}
  545.  
  546.             {$Push} {$J+}
  547.             gToolBoxInitialized: BOOLEAN;                { Indicates whether toolbox has been inited
  548.                                                          }
  549.             gUDialogInitialized: BOOLEAN;                { Indicates whether UDialog has been inited
  550.                                                          }
  551.             gUGridViewInitialized: BOOLEAN;             { Indicates whether UGridView has been
  552.                                                          inited }
  553.             gUPrintingInitialized: BOOLEAN;             { Indicates whether UPrinting has been
  554.                                                          inited }
  555.             gUTEViewInitialized: BOOLEAN;                { Indicates whether UTEView has been inited
  556.                                                          }
  557.             gStrippedAddress:    Ptr;                    { an address already stripped by
  558.                                                          StripAddress }
  559.             {$Pop}
  560.  
  561.             gRGBBlack,                                    { RGB representation for black. }
  562.             gRGBWhite:            RGBColor;                { RGB representation for white. }
  563.             gCursorRgn:         RgnHandle;                { the current cursor region that will be
  564.                                                          passed to WaitNextEvent as the sleep
  565.                                                          region }
  566.             gDeadStripSuppression: BOOLEAN;             { Dynamically set to false. Condition the
  567.                                                          execution of a New(aTFoo) to suppress the
  568.                                                          dead-stripping of support for a TFoo }
  569.             gCreateWithTemplates: BOOLEAN;                { Same as gDeadStripSuppression. Left in for
  570.                                                          compatibility (2.0) }
  571.  
  572.             gMATextBoxTE:        TEHandle;                { a working TEHandle for use exclusively by
  573.                                                          MATextBox. Keeps us from having to
  574.                                                          continually allocate and dispose a TE
  575.                                                          (like TextBox does) }
  576.  
  577.             gTEDefaultWordBreak: ProcPtr;                { The default word break routine used by TE.
  578.                                                          NOTE that _this_ routine (alone) does not
  579.                                                          take parameters using the Pascal calling
  580.                                                          conventions as required by SetWordBreak
  581.                                                          (Thank you TE!) and must be set in the TE
  582.                                                          by munging (Rhymes with plunging) the
  583.                                                          wordBreak field directly. }
  584.  
  585.             { S T A R T U P   U T I L I T I E S }
  586.  
  587.         PROCEDURE InitToolBox;
  588.         { Essential toolbox and utility initialization. }
  589.  
  590.         PROCEDURE DefineConfiguration(VAR configuration: ConfigRecord);
  591.         { Fills the configuration record for the host machine. }
  592.  
  593.         FUNCTION ValidateConfiguration(configuration: ConfigRecord): BOOLEAN;
  594.         { FALSE if compiled configuration doesn't match runtime config }
  595.  
  596.         { M I S C E L L A N E O U S   U T I L I T I E S }
  597.  
  598.         { >>> NOTE <<<
  599.  
  600.         Use the following accessors _wisely_ since they can play real havoc with inter-language
  601.         portability. These routines used to begin with %_ but, that was dropped since it translates
  602.         into the reserved __ in C++.
  603.  
  604.         }
  605.  
  606.         FUNCTION GetParmBlockPtr: LONGINT;
  607.             INLINE $2E88;                                { MOVE.L A0,(A7) }
  608.         { Formerly, %_GetA0. Return the value of register A0.  Useful for getting the pointer
  609.         to the parameter block from a VBL task or a completion routine. }
  610.  
  611.         FUNCTION GetA5: LONGINT;
  612.             INLINE $2E8D;                                { MOVE.L A5,(A7) }
  613.         { Formerly, %_GetA5. Return the value of register A5. Useful for getting the immediate value
  614.         of A5 which is not always the same as CurrentA5.  Generally a pointer to the program's
  615.         global area and jump table. }
  616.  
  617.         FUNCTION GetCurStackFramePtr: Ptr;
  618.             INLINE $2E8E;                                { MOVE.L A6,(A7) }
  619.         { Formerly, %_GetA6. Return the value of register A6.  Usually a pointer to the local stack
  620.         frame.    Most often used to find out the caller's name when invoking a debugging routine. }
  621.  
  622.         FUNCTION GetCurStackTop: Ptr;
  623.             INLINE $2E8F;                                { MOVE.L A7,(A7) }
  624.         { Formerly, %_GetA7. Return the value of register A7.  Usually the top of stack.  Useful
  625.         for stack sniffing (not a crime). }
  626.  
  627.       {--------------------------------------------------------------------------------------------}
  628.  
  629.         PROCEDURE BlockSet(destPtr: Ptr;
  630.                            byteCount: LONGINT;
  631.                            setVal: UNIV SignedByte);
  632.         { Sets a block of memory to a value.  }
  633.  
  634.         PROCEDURE CenterRectOnScreen(VAR aRect: Rect;
  635.                                      horizontally, vertically, forDialog: BOOLEAN);
  636.         { Horizontally and/or vertically centers the given rectangle on the main screen. If forDialog
  637.         is true then the rect is vertically centered closer to the top of the screen as for a modal
  638.         dialog. }
  639.  
  640.         FUNCTION CompareStrings(first, second: Str255): INTEGER;
  641.         { Returns -1, 0, or 1 if first <, =, or > second. }
  642.  
  643.         PROCEDURE CopyStr255(VAR fmStr: Str255;
  644.                              toAddr: UNIV Ptr);
  645.         { Copies a string, copying ONLY what's necessary }
  646.  
  647.         PROCEDURE EachWMgrWindowDo(PROCEDURE DoToWMgrWindow(theWMgrWindow: WindowPtr));
  648.         { Calls DoToWMgrWindow for each window in the windowlist starting at FrontWindow.  }
  649.  
  650.         FUNCTION FindWindowBefore(theWindow: WindowPtr): WindowPtr;
  651.         { returns the window just before a given window. Returns nil if the given window is frontmost
  652.         or not found. }
  653.  
  654.         FUNCTION PRStr(astr: Str255): Ptr;
  655.             INLINE $2E9F;                                { Move.L (A7)+,(A7) }
  656.         { For brain-damaged compiler, which can't pass the address of a string in a packed record,
  657.         even though it has to be byte-aligned by definition. Sure, maybe it's not word aligned, but for a
  658.         BlockMove we don't care. When calling CopyStr255 where the destination is the address of a
  659.         Str255 in a packed record, call it like this: CopyStr255(fromStr, PRStr(packedStr)); }
  660.  
  661.         FUNCTION AtStr(astr: Str255): StringPtr;
  662.             INLINE $2E9F;                                { Move.L (A7)+,(A7) }
  663.         { Lets you take the address of a string constant so you can pass pointers with no stack copy.
  664.         Use it like this: AtStr('Foo'); }
  665.  
  666.         FUNCTION AtMAName(astr: MAName): MANamePtr;
  667.             INLINE $2E9F;                                { Move.L (A7)+,(A7) }
  668.         { Lets you take the address of a string constant so you can pass pointers with no stack copy.
  669.         Use it like this: AtMAName('Bar'); }
  670.  
  671.         PROCEDURE PullApplicationToFront;
  672.         { Applications don't start as the frontmost layer under MultiFinder™. They come to the front
  673.         after a few Event calls. If you have a splash screen at startup then you probably want to
  674.         use this call. }
  675.  
  676.         PROCEDURE DefaultSize(VAR theSize: INTEGER);
  677.         { If theSize is equal to the system font size then theSize is set to zero. Otherwise it is
  678.         left unchanged. The purpose of this routine is to convert a font size to portable form,
  679.         where a font size of zero is the portable equivalent to the system font size. }
  680.  
  681.         FUNCTION DisposeIfHandle(aHandle: UNIV Handle): Handle;
  682.         { Disposes the handle only if it is non-NIL.
  683.         Returns NIL for convenient assignment back to the reference passed in. } { Preferred }
  684.  
  685.         FUNCTION DisposeIfPtr(aPtr: UNIV Ptr): Ptr;
  686.         { Disposes the pointer only if it is non-NIL.
  687.         Returns NIL for convenient assignment back to the reference passed in. } { Preferred }
  688.  
  689.         PROCEDURE DisposIfHandle(aHandle: UNIV Handle); { Left in for compatibility (2.0) }
  690.  
  691.         PROCEDURE DisposIfPtr(aPtr: UNIV Ptr);            { Left in for compatibility (2.0) }
  692.  
  693.         FUNCTION EqualBlocks(first, second: UNIV Ptr;
  694.                              theSize: INTEGER): BOOLEAN;
  695.         { Returns true if the two blocks pointed at by first and second are equal over theSize
  696.         bytes.}
  697.  
  698.         PROCEDURE FieldToString(theData: Ptr;
  699.                                 fieldType: INTEGER;
  700.                                 VAR theString: Str255);
  701.         { Calls the routine whose address is stored in gFieldToStrRtn. Its purpose is to take some
  702.         data pointed to by theData, and whose type is indicated by field type, and convert that
  703.         data into a string representation. By default, gFieldToStrRtn points to StdFieldToString. }
  704.  
  705.         FUNCTION GetActualJustification(justification: INTEGER): INTEGER;
  706.         { If the justification passed in is teJustSystem then returns teJustLeft or teJustRight
  707.         depending on the setting of the system justification.  Other justifications are just passed
  708.         through to the result. }
  709.  
  710.         FUNCTION GetFontNum(fontName: Str255): INTEGER;
  711.         { Returns the font number corresponding to the given name. If fontName is equal to
  712.         kSysFontName then zero is returned. If fontName is equal to kApplFontName then 1 is
  713.         returned. Otherwise the Toolbox routine GetFNum is called to get the font number. }
  714.  
  715.         FUNCTION GetHandleBits(h: Handle): SignedByte;
  716.         { Return the flag byte of a handle.  Left in for compatibility (2.0) }
  717.  
  718.         {$IFC NOT qNeedsColorQD}
  719.  
  720.         PROCEDURE GetIfColor(VAR aColor: RGBColor);
  721.         { If flag qNeedsColorQD is FALSE then use this method, otherwise use the one below. }
  722.         {$ELSEC}
  723.  
  724.         PROCEDURE GetIfColor(VAR aColor: RGBColor);
  725.             INLINE _GetForeColor;
  726.         {$ENDC}
  727.         { Fetches current foreground color.  Works for both old and new QuickDraw. }
  728.  
  729.         {$IFC NOT qNeedsColorQD}
  730.  
  731.         PROCEDURE GetIfBkColor(VAR aColor: RGBColor);
  732.         { If flag qNeedsColorQD is FALSE then use this method, otherwise use the one below. }
  733.         {$ELSEC}
  734.  
  735.         PROCEDURE GetIfBkColor(VAR aColor: RGBColor);
  736.             INLINE _GetBackColor;
  737.         {$ENDC}
  738.         { Fetches current background color.  Works for both old and new QuickDraw. }
  739.  
  740.         PROCEDURE GetPortTextStyle(VAR theTextStyle: TextStyle);
  741.         { Returns the textStyle representing the current state of thePort. }
  742.  
  743.         PROCEDURE GetPortFontInfo(fontNum: INTEGER;
  744.                                   VAR fontName: Str255;
  745.                                   VAR fontSize: INTEGER);
  746.         { Returns the font name corresponding to a given name, in portable format. i.e. if fontNum is
  747.         the system font then kSysFontName is returned; if fontNum is the application font then
  748.         kApplFontName is return; otherwise the Toolbox routine GetFontName is called to get the
  749.         font name. Then, if fontNum is the system or application font, a 0 is returned if the size
  750.         is the default size. }
  751.  
  752.         FUNCTION GetTrapType(theTrap: INTEGER): TrapType;
  753.         { Returns the trap's type (OSTrap or ToolTrap). }
  754.  
  755.         FUNCTION IntMultiply(x, y: INTEGER): LONGINT;
  756.             INLINE $301F,                                { MOVE.W (A7)+,D0 }
  757.                    $C1DF,                                { MULS.W (A7)+,D0 }
  758.                    $2E80;                                { MOVE.L D0,(A0) }
  759.         { Multiplies two integers and returns a longint result. Note that the Pascal compiler will
  760.         generate a 16-bit result if you say n := x * y, truncating the upper 16-bits. Furthermore,
  761.         if either x or y is a longint then the compiler expands both operands to 32-bits and calls
  762.         a 32-bit multiply subroutine. IntMultiply avoids these problems. }
  763.  
  764.         FUNCTION IsHandle(h: UNIV Handle): BOOLEAN;
  765.         { Returns true or false for handlehood of h }
  766.  
  767.         FUNCTION IsHandleLocked(h: UNIV Handle): BOOLEAN;
  768.         { Returns lockState of h }
  769.  
  770.         {$IFC qDebug}
  771.  
  772.         FUNCTION IsHandlePurged(h: UNIV Handle): BOOLEAN;
  773.         { Returns purgeState of h }
  774.         {$ElseC}
  775.  
  776.         FUNCTION IsHandlePurged(h: UNIV Handle): BOOLEAN;
  777.             INLINE $205F,                                { MOVE.L (A7)+,A0 }
  778.                    $4A90,                                { TST.L (A0) }
  779.                    $57D7,                                { SEQ (A7) }
  780.                    $4417;                                { NEG.B (A7) }
  781.         { Returns purgeState of h }
  782.         {$EndC}
  783.  
  784.         FUNCTION LengthRect(r: Rect;
  785.                             vhs: VHSelect): INTEGER;
  786.         { If vhs is v, returns the length of r; else returns the width of r. }
  787.  
  788.         PROCEDURE LockHandleHigh(h: Handle);
  789.         { Convenience function.  Moves a handle high (MoveHHi) and locks it (HLock).  The two
  790.         operations are very frequently performed together thus, this procedure.  Ignores NIL
  791.         handles. }
  792.  
  793.         FUNCTION LongerSide(VAR r: Rect): VHSelect;
  794.         { Return an indication of which side is longer. }
  795.  
  796.         PROCEDURE LIntToHex(decNumber: UNIV LONGINT;
  797.                             VAR hexNumber: String8;
  798.                             noOfDigits: INTEGER);
  799.         { LIntToHex converts decNumber to a hexidecimal string of noOfDigits length. }
  800.  
  801.         FUNCTION MAUseResFile(refNum: INTEGER): INTEGER;
  802.         { Like the ToolBox UseResFile but, it also returns the old CurResFile setting }
  803.  
  804.         PROCEDURE MATextBox(text: Ptr;
  805.                             itsLength: LONGINT;
  806.                             box: Rect;
  807.                             itsJust: INTEGER;
  808.                             autoWrap: BOOLEAN;
  809.                             wordBreak: ProcPtr;
  810.                             eraseFirst: BOOLEAN;
  811.                             spaceForCaret: BOOLEAN);
  812.         { Like the toolbox TextBox but, it also gives you control over whether the text should
  813.         word-wrap with autoWrap, whether the box should be erased first with eraseFirst and, if
  814.         word-wrap is specified, where the word breaks should be with wordBreak (pass NIL to use
  815.         the default word-wrap routine in TE.  Since TextBox uses TE to image the text,
  816.         spaceForCaret lets us adjust the drawn text by 1 pixel (the insertion caret) on the left and
  817.         right.  If the text is editable or could become editable (as in TEditText) you probably want
  818.         to leave space for a caret.  If the text is a title or something then you probably don't
  819.         want to leave space for a caret.}
  820.  
  821.         PROCEDURE MADrawString(s: StringPtr; box: Rect; justification: INTEGER);
  822.         { A convenience routine.  Like the toolbox DrawString but, it uses a StringPtr to help
  823.         reduce stack space requirements. And It also gives you control over
  824.         the bounds into which the text will be drawn and draws it in the correct international
  825.         direction.  This routine is _MUCH_ slower than DrawString. }
  826.  
  827.         FUNCTION Max(a, b: LONGINT): LONGINT;
  828.             INLINE $201F,                                { MOVE.L (A7)+,D0 }
  829.                    $2E9F,                                { MOVE.L (A7)+,(A7) }
  830.                    $B097,                                { CMP.L (A7),D0 }
  831.                    $6F02,                                { BGE.S *+4 }
  832.                    $2E80;                                { MOVE.L D0,(A7) }
  833.         { Returns the maximum of a and b. }
  834.  
  835.         FUNCTION Min(a, b: LONGINT): LONGINT;
  836.             INLINE $201F,                                { MOVE.L (A7)+,D0 }
  837.                    $2E9F,                                { MOVE.L (A7)+,(A7) }
  838.                    $B097,                                { CMP.L (A7),D0 }
  839.                    $6C02,                                { BLE.S *+4 }
  840.                    $2E80;                                { MOVE.L D0,(A7) }
  841.         { Returns the minimum of a and b. }
  842.  
  843.         FUNCTION MinMax(MinVal, expression, MaxVal: LONGINT): LONGINT;
  844.         { Returns the expression bounded by minimum and maximum }
  845.  
  846.         PROCEDURE NumberToHex(theNumber: UNIV LONGINT;
  847.                               VAR hexString: Str255;
  848.                               hexDigits: INTEGER);
  849.         { Converts theNumber to a hex string preceeded with '$'.}
  850.  
  851.         FUNCTION PinOnRect(theRect: Rect;
  852.                            thePt: Point): LONGINT;
  853.         { Like PinRect except that if thePt.h (or v) is >= theRect.right (bottom) it returns
  854.         theRect.right (bottom). PinRect returns 1 less than that except if thePt is exactly on the
  855.         edge of theRect.}
  856.  
  857.         FUNCTION StripLong(address: UNIV Ptr): LONGINT;
  858.         { same function as the glue/trap stripAddress only the types are long and modified to bypass
  859.         the inefficient MPW glue!!.  If inlines could reference relocatables it could even be inline. }
  860.  
  861.         PROCEDURE PointerToHex(theNumber: UNIV LONGINT;
  862.                                VAR hexString: Str255;
  863.                                hexDigits: INTEGER);
  864.         { If theNumber is zero, then hexString is set to 'Nil'. Else theNumber is converted to a hex
  865.         string preceeded with '$'.}
  866.  
  867.         FUNCTION RectsNest(outer, inner: Rect): BOOLEAN;
  868.         { Determine if inner nests within outer. }
  869.  
  870.         FUNCTION VRectsNest(outer, inner: VRect): BOOLEAN;
  871.         { Determine if inner nests within outer for VCoordinates. }
  872.  
  873.         FUNCTION RoundUp(aNumber: LONGINT;
  874.                          aModulus: INTEGER): LONGINT;
  875.         { Rounds aNumber up so that it is evenly divisible by aModulus. }
  876.  
  877.         FUNCTION SetKeyScript(newKeyScript: INTEGER): INTEGER;
  878.         { If newKeyScript is different from the current key script, then the key script is set to
  879.         newKeyScript. (The reason we don't want to set the key script to the same thing is that the
  880.         Script Mgr. does a FlushEvents when it sets the key script.) }
  881.  
  882.         PROCEDURE SetHandleBits(h: Handle;
  883.                                 theBits: SignedByte);
  884.         { Sets the flag byte of a handle. Left in for compatibility (2.0) }
  885.  
  886.         {$IFC NOT qNeedsColorQD}
  887.  
  888.         PROCEDURE SetIfColor(aColor: RGBColor);
  889.         { If flag qNeedsColorQD is FALSE then use this method, otherwise use the one below. }
  890.         {$ELSEC}
  891.  
  892.         PROCEDURE SetIfColor(aColor: RGBColor);
  893.             INLINE _RGBForeColor;
  894.         {$ENDC}
  895.         { Sets foreground color.  Works for both old and new QuickDraw. }
  896.  
  897.         {$IFC NOT qNeedsColorQD}
  898.  
  899.         PROCEDURE SetIfBkColor(aColor: RGBColor);
  900.         { If flag qNeedsColorQD is FALSE then use this method, otherwise use the one below. }
  901.         {$ELSEC}
  902.  
  903.         PROCEDURE SetIfBkColor(aColor: RGBColor);
  904.             INLINE _RGBBackColor;
  905.         {$ENDC}
  906.         { Sets background color.  Works for both old and new QuickDraw. }
  907.  
  908.         PROCEDURE SetPortTextStyle(theTextStyle: TextStyle);
  909.         { Sets the font style of the current port to the characteristics of theTextStyle. }
  910.  
  911.         PROCEDURE SetRGBColor(VAR RGB: RGBColor;
  912.                               red, green, blue: INTEGER);
  913.         { Sets RGB to the given colors. }
  914.  
  915.         PROCEDURE SetTextStyle(VAR theTextStyle: TextStyle;
  916.                                theFont: INTEGER;
  917.                                theStyle: Style;
  918.                                theSize: INTEGER;
  919.                                theColor: RGBColor);
  920.         { Sets theTextStyle to the given characteristics }
  921.  
  922.         PROCEDURE StdFieldToString(theData: Ptr;
  923.                                    fieldType: INTEGER;
  924.                                    VAR theString: Str255);
  925.         { This routine converts all field types defined by the constants in this unit. }
  926.  
  927.         PROCEDURE ScrapStuffFields(aTitle: Str255;
  928.                                    VAR aScrapStuff: ScrapStuff;
  929.                                    PROCEDURE DoToField(fieldName: Str255;
  930.                                                        fieldAddr: Ptr;
  931.                                                        fieldType: INTEGER));
  932.         { Used to inspect the fields of a ScrapStuff. }
  933.  
  934.         PROCEDURE TextStyleFields(aTitle: Str255;
  935.                                   VAR aStyle: TextStyle;
  936.                                   PROCEDURE DoToField(fieldName: Str255;
  937.                                                       fieldAddr: Ptr;
  938.                                                       fieldType: INTEGER));
  939.         { Used to inspect the fields of a TextStyle record. }
  940.  
  941.         PROCEDURE ConfigRecFields(aTitle: Str255;
  942.                                   VAR aConfigRec: ConfigRecord;
  943.                                   PROCEDURE DoToField(fieldName: Str255;
  944.                                                       fieldAddr: Ptr;
  945.                                                       fieldType: INTEGER));
  946.         { Used to inspect the fields of a Config record. }
  947.  
  948.         FUNCTION TrapExists(theTrap: INTEGER): BOOLEAN;
  949.         { Returns true if the given trap exists at run-time }
  950.  
  951.         FUNCTION UprChar(ch: CHAR): CHAR;
  952.         { Returns ch converted to upper case }
  953.  
  954.         PROCEDURE UprStr255(VAR s: Str255);
  955.         { Converts s to all upper case. }
  956.  
  957.         PROCEDURE UprMAName(VAR s: MAName);
  958.         { Converts s to all upper case. }
  959.  
  960.         FUNCTION LowerChar(ch: CHAR): CHAR;
  961.         { Returns ch converted to lower case }
  962.  
  963.         PROCEDURE LowerStr255(VAR s: Str255);
  964.         { Converts s to all lower case. }
  965.  
  966.         PROCEDURE UseSelectionColor;
  967.             INLINE $08B8, $0007, kLMHiliteMode;         { BCLR #$07,kLMHiliteMode }
  968.         { Call to make the next (and only the next) QD operation use the selection color. }
  969.  
  970.         PROCEDURE UseROMMap(resLoad: BOOLEAN);
  971.         { Call this before any Resource Manager call for which you might like to use ROM resources.
  972.         Remember, if you pass FALSE to this then you should call SetResLoad(TRUE) afterwards. }
  973.  
  974.         PROCEDURE WithApplicationResFileDo(PROCEDURE DoWithResFile);
  975.         { Performs a proc with the application res file as the curResFile restoring the prev setting
  976.         at completion. }
  977.  
  978.         { F I L E    U T I L I T I E S }
  979.  
  980.         FUNCTION CloseFile(dataRefnum, rsrcRefnum: INTEGER): OSErr;
  981.         { Closes the data and resource forks of a file. If dataRefnum = kNoFileRefnum then the data
  982.         fork is not closed. Likewise, if rsrcRefnum = kNoFileRefnum then the resource fork is not
  983.         closed. Returns noErr if successful, else an O.S. error. }
  984.  
  985.         FUNCTION DeleteFile(namePtr: StringPtr;
  986.                             volRefnum: INTEGER): OSErr;
  987.         { Deletes the specified file; uses FillInDirID to bypass the Poor Man's Search Path. }
  988.  
  989.         FUNCTION FileModDate(name: Str255;
  990.                              volRefnum: INTEGER): LONGINT;
  991.         { Returns file modification date or 0 if an I/O error occurs }
  992.  
  993.         FUNCTION FillInDirID(pb: HParmBlkPtr): OSErr;
  994.         { Based on the ioVRefnum field of pb^, looks up the dirID of the working directory and fills
  995.         it into the ioDirID field. If HFS is not installed, it sets the ioDirID to 0. This is used
  996.         to inhibit the PMSP. After setting up your HParamBLockRec, call this to fill in the dirID
  997.         and then make the H form of the call (eg., PBHGetFInfo rather than PBGetFInfo). }
  998.  
  999.         FUNCTION GetDirID(VAR vRefnum: INTEGER;
  1000.                           VAR dirID: LONGINT): OSErr;
  1001.         { Returns the dirID corresponding to a given wdRefnum; changes vRefnum to be a real volume
  1002.         refnum. }
  1003.  
  1004.         FUNCTION GetFileInfo(name: Str255;
  1005.                              volRefnum: INTEGER;
  1006.                              VAR info: HParamBlockRec): OSErr;
  1007.         { Makes a PBHGetFInfo call, and returns result in info. Bypasses PMSP. }
  1008.  
  1009.         FUNCTION NumBlocks(numBytes: LONGINT;
  1010.                            blkSize: LONGINT): LONGINT;
  1011.         { Returns the number of blocks required to store numBytes, given that the block size is
  1012.         blkSize. }
  1013.  
  1014.         FUNCTION MAOpenFile(name: Str255;
  1015.                             volRefnum: INTEGER;
  1016.                             openData, openRsrc: BOOLEAN;
  1017.                             dataPerm, rsrcPerm: INTEGER;
  1018.                             VAR dataRefnum, rsrcRefnum: INTEGER): OSErr;
  1019.         { Open the specified forks of the file using the specified permissions. Returns kNoFileRefnum
  1020.         for refnums that are not (or cannot) be opened. On 64K ROM machines, rsrcPerm is ignored.
  1021.         Returns an O/S error if the data fork does not exist; returns a rsrcRefnum of kNoFileRefnum
  1022.         if the resource fork does not exist. Returns an O/S error for all other errors. If no error
  1023.         occurs, returns NoErr. }
  1024.  
  1025.         { D E B U G G I N G   U T I L I T I E S }
  1026.  
  1027.         FUNCTION ConcatNumber(aString: Str255;
  1028.                               aNumber: LONGINT): Str255;
  1029.         { Returns aString appended with the string representation of aNumber }
  1030.  
  1031.         FUNCTION CanReadLn: BOOLEAN;
  1032.         { returns TRUE if WritelnWindow is available and the display is not suppressed }
  1033.  
  1034.         FUNCTION CanWriteLn: BOOLEAN;
  1035.         { returns TRUE if WritelnWindow is available }
  1036.  
  1037.         FUNCTION ReadInteger(prompt: Str255): INTEGER;
  1038.         { Displays prompt and reads an integer from the debug window. }
  1039.  
  1040.         FUNCTION ReadYesNo(prompt: Str255): BOOLEAN;
  1041.         { Displays prompt and accepts a 'y' or 'n' as input from the debug
  1042.         window. }
  1043.  
  1044.         FUNCTION VerboseIsHandle(h: UNIV Handle): BOOLEAN;
  1045.         { Returns true if h is really a handle. If not then it prints diagnostic info about the
  1046.         alleged handle. }
  1047.  
  1048.         PROCEDURE WritePt(pt: Point);
  1049.         { Writes the point in the debug window. }
  1050.  
  1051.         PROCEDURE WritePtr(val: UNIV LONGINT);
  1052.         { Writes the pointer, in hex, in the debug window. }
  1053.  
  1054.         PROCEDURE WriteRect(r: Rect);
  1055.         { Writes the rectangle in the debug window. }
  1056.  
  1057.         PROCEDURE WriteBoolean(b: BOOLEAN);
  1058.         { Writes the boolean in the debug window. }
  1059.  
  1060.         PROCEDURE WriteVPt(pt: VPoint);
  1061.         { Writes the VPoint in the debug window. }
  1062.  
  1063.         PROCEDURE WriteVRect(r: VRect);
  1064.         { Writes the VRect in the debug window. }
  1065.  
  1066.         PROCEDURE WrLblPt(aLabel: Str255;
  1067.                           pt: Point);
  1068.         { Writes the label, ' = ', the point, to the debug window. }
  1069.  
  1070.         PROCEDURE WrLblPtr(aLabel: Str255;
  1071.                            val: UNIV LONGINT);
  1072.         { Writes the label, ' = ', the pointer in hex, to the debug window. }
  1073.  
  1074.         PROCEDURE WrLblRect(aLabel: Str255;
  1075.                             r: Rect);
  1076.         { Writes the label, ' = ', the rectangle, to the debug window. }
  1077.  
  1078.         PROCEDURE WrLblBoolean(aLabel: Str255;
  1079.                                b: BOOLEAN);
  1080.         { Writes the label, ' = ', the boolean, to the debug window. }
  1081.  
  1082.         PROCEDURE WrLblVPt(aLabel: Str255;
  1083.                            pt: VPoint);
  1084.         { Writes the label, ' = ', the VPoint in the debug window. }
  1085.  
  1086.         PROCEDURE WrLblVRect(aLabel: Str255;
  1087.                              r: VRect);
  1088.         { Writes the lable, ' = ', the VRect in the debug window. }
  1089.  
  1090.         PROCEDURE WriteSig(theID: IDType);
  1091.         { Writes out an IDType signature. }
  1092.  
  1093.         PROCEDURE WrLblSig(theLabel: Str255;
  1094.                            theID: IDType);
  1095.         { Writes the label, ' =', theID in the debug window. }
  1096.  
  1097.         PROCEDURE WrLblHandleContents(aLabel: Str255;
  1098.                                       theHandle: UNIV Handle);
  1099.         { Writes the label, ' =', theHandle in the debug window. }
  1100.  
  1101.         PROCEDURE WriteHandleContents(theHandle: UNIV Handle);
  1102.         { Writes theHandle    in the debug window. }
  1103.  
  1104.         PROCEDURE WriteHexInt(theInt: INTEGER);
  1105.         { Writes theInt  in the debug window. }
  1106.  
  1107.         PROCEDURE WrLblHexInt(theLabel: Str255;
  1108.                               theInt: INTEGER);
  1109.         { Writes the label, ' =', theInt in the debug window. }
  1110.  
  1111.         PROCEDURE WriteHexLongint(theLongint: LONGINT);
  1112.         { Writes theLongint  in the debug window. }
  1113.  
  1114.         PROCEDURE WrLblHexLongint(theLabel: Str255;
  1115.                                   theLongint: LONGINT);
  1116.         { Writes the label, ' =', theLongint in the debug window. }
  1117.         {$ENDC}
  1118.  
  1119.         {$IFC NOT UsingIncludes}
  1120. END.
  1121. {$ENDC}
  1122.